<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta name="generator" content="rustdoc">
    <title>Native Windows GUI guide - Multithreading</title>

    <link rel="stylesheet" type="text/css" href="style/rustbook.css">
    <link rel="stylesheet" type="text/css" href="style/pygments.css">
    <link rel="stylesheet" type="text/css" href="style/nwg.css">


</head>
<body class="rustdoc">
<!--[if lte IE 8]>
<div class="warning">
    This old browser is unsupported and will most likely display funky
    things.
</div>
<![endif]-->

<!-- NAV BEGIN -->
<div id="nav">
    <button id="toggle-nav">
        <span class="sr-only">Toggle navigation</span>
        <span class="bar"></span>
        <span class="bar"></span>
        <span class="bar"></span>
    </button>
</div>

    
<div id='toc' class='mobile-hidden'>
<ul class='chapter'>
<li><a href='index.html'><b>1.</b> Introduction</a>
</li>
<li><a href='getting_started.html'><b>2.</b> Getting Started</a>
</li>

<li><a href="basics.html"><b>3.</b> Basics </a>
<ul class="section">
    <li><a href="controls.html"><b>3.1.</b> Controls </a></li>
    <li><a href="events.html"><b>3.2.</b> Events </a></li>
    <li><a href="helper.html"><b>3.3.</b> Helpers </a></li>
    <li><a href="small.html"><b>3.4.</b> Small application layout </a></li>
    <li><a href="limitations.html"><b>3.5.</b> Limitations </a></li>
    <li><a href="distribute.html"><b>3.6.</b> Distributing </a></li>
</ul>
</li>

<li><a href="intermediate.html"><b>4.</b> Intermediate </a>
<ul class="section">
    <li><a href="layouts.html"><b>4.1.</b> Layouts </a></li>
    <li><a href="resources.html"><b>4.2.</b> Resources </a></li>
    <li><a href="dialogs.html"><b>4.3.</b> Dialogs </a></li>
    <li><a href="localization.html"><b>4.4.</b> Internationalization </a></li>
</ul>
</li>

<li><a href="advanced.html"><b>5.</b> Advanced </a>
<ul class="section">
    <li><a href="partial.html"><b>5.1.</b> Partials ui </a></li>
    <li><a href="dynamic_control.html"><b>5.2.</b> Dynamic control </a></li>
    <li><a href="dynamic_event.html"><b>5.3.</b> Dynamic events </a></li>
    <li><a href="multithreading.html"><b>5.4.</b> Multithreading </a></li>
</ul>
</li>

<li><a href="derive.html"><b>6.</b> Native-windows-derive </a>
<ul class="section">
    <li><a href="nwd_basics.html"><b>6.1.</b> Basics </a></li>
    <li><a href="nwd_controls.html"><b>6.1.</b> Controls </a></li>
    <li><a href="nwd_resources.html"><b>6.2.</b> Resources </a></li>
    <li><a href="nwd_events.html"><b>6.3.</b> Events </a></li>
    <li><a href="nwd_layouts.html"><b>6.4.</b> Layouts </a></li>
    <li><a href="nwd_partial.html"><b>6.5.</b> Partials </a></li>
</ul>
</li>

<li><a href="low.html"><b>7.</b> Low level stuff </a>
    <ul class="section">
        <li><a href="low_events.html"><b>7.1.</b> Raw event handling </a></li>
        <li><a href="extern_wrapping.html"><b>7.2.</b> Raw control handle </a></li>
    </ul>
</li>

</ul>
</div>
<!-- NAV END -->

<div id='page-wrapper'>
    <div id='page'>

        <h1 class="title">Native Windows GUI: Multithreading</h1>

        Win32 is a single threaded API. That means a window and all it's children control will be contained on a single thread (the GUI thread).
        This is a problem is an application has a method that blocks the GUI thread (ex: reading a large file) because doing so will make the UI
        unusable for the duration of the method. This section will explain how NWG fix this problem.<br><br>

        <h3>The notice object</h3>  

        Assuming there is a task that will block the UI thread. It's obvious the first step would be to just move this task into another thread.
        But then, how does the main thread will know when the task is completed? The answer is the <code>Notice</code> object.<br><br>

        (Using notice objects require the <code>notice</code> feature.)<br><br>

        The <code>Notice</code> object is an invisible component that can send a message to their window from another thread. Here's a very simple example on how to use it:

<div class="highlight"><pre  style="width: auto;"><span></span><span class="k">pub</span><span class="w"> </span><span class="k">struct</span> <span class="nc">HeavyCompute</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">    </span><span class="n">window</span>: <span class="nc">nwg</span>::<span class="n">Window</span><span class="p">,</span><span class="w"></span>
<span class="w">    </span><span class="n">notice</span>: <span class="nc">nwg</span>::<span class="n">Notice</span><span class="p">,</span><span class="w"></span>
<span class="w">    </span><span class="n">compute</span>: <span class="nc">RefCell</span><span class="o">&lt;</span><span class="nb">Option</span><span class="o">&lt;</span><span class="n">thread</span>::<span class="n">JoinHandle</span><span class="o">&lt;</span><span class="kt">u64</span><span class="o">&gt;&gt;&gt;</span><span class="p">,</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>

<span class="c1">// ... NativeUi implementation ... </span>

<span class="sd">/// `Event::OnWindowInit` callback</span>
<span class="k">fn</span> <span class="nf">on_init</span><span class="p">(</span><span class="n">app</span>: <span class="kp">&amp;</span><span class="nc">HeavyCompute</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">    </span><span class="kd">let</span><span class="w"> </span><span class="n">sender</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">app</span><span class="p">.</span><span class="n">notice</span><span class="p">.</span><span class="n">sender</span><span class="p">();</span><span class="w"></span>
<span class="w">    </span><span class="o">*</span><span class="bp">self</span><span class="p">.</span><span class="n">compute</span><span class="p">.</span><span class="n">borrow_mut</span><span class="p">()</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="nb">Some</span><span class="p">(</span><span class="n">thread</span>::<span class="n">spawn</span><span class="p">(</span><span class="k">move</span><span class="w"> </span><span class="o">||</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">        </span><span class="n">thread</span>::<span class="n">sleep</span><span class="p">(</span><span class="n">Duration</span>::<span class="n">new</span><span class="p">(</span><span class="mi">5</span><span class="p">,</span><span class="w"> </span><span class="mi">0</span><span class="p">));</span><span class="w"></span>
<span class="w">        </span><span class="n">sender</span><span class="p">.</span><span class="n">notice</span><span class="p">();</span><span class="w"></span>
<span class="w">        </span><span class="mi">1</span><span class="o">+</span><span class="mi">1</span><span class="w"></span>
<span class="w">    </span><span class="p">}));</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>

<span class="sd">/// `Event::OnNotice` callback</span>
<span class="k">fn</span> <span class="nf">on_notice</span><span class="p">(</span><span class="n">app</span>: <span class="kp">&amp;</span><span class="nc">HeavyCompute</span><span class="p">)</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">    </span><span class="kd">let</span><span class="w"> </span><span class="k">mut</span><span class="w"> </span><span class="n">data</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">app</span><span class="p">.</span><span class="n">compute</span><span class="p">.</span><span class="n">borrow_mut</span><span class="p">();</span><span class="w"></span>
<span class="w">    </span><span class="k">match</span><span class="w"> </span><span class="n">data</span><span class="p">.</span><span class="n">take</span><span class="p">()</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">        </span><span class="nb">Some</span><span class="p">(</span><span class="n">data</span><span class="p">)</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">            </span><span class="n">println</span><span class="o">!</span><span class="p">(</span><span class="s">&quot;THE ANSWER IS {:?}!&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">data</span><span class="p">);</span><span class="w"></span>
<span class="w">        </span><span class="p">},</span><span class="w"></span>
<span class="w">        </span><span class="nb">None</span><span class="w"> </span><span class="o">=&gt;</span><span class="w"> </span><span class="p">{}</span><span class="w"></span>
<span class="w">    </span><span class="p">}</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>
</pre></div>
        
        <br>
            
        In this example, a heavy compute operation is started off the main thread after window initialization.<br>
        
        <ol>
            <li><code>on_init</code> generates a <code>NoticeSender</code> from the application notice</li>
            <li>The <code>NoticeSender</code> is sent to another thread</li>
            <li>The thread handle is saved in the application to read from it later</li>
            <li>Once the off-thread computation are done, <code>sender.notice()</code> is called to wake up the notice on the main GUI thread</li>
            <li>Finally, the <code>OnNotice</code> event is raised and the compute thread is joined to get the compute value</li>
        </ol>

        <br>

        <h3>Running windows on multiple threads</h3> 

        NWG does not have any global state. As such it's possible to create as many GUI thread as you might want. Each GUI thread can have its own windows.
        Blocking one of the GUI thread won't block the second. This is useful when implementing dialogs.<br><br>

        <h3>Example</h3>

        <ul>
            <li><a href="https://github.com/gabdube/native-windows-gui/blob/master/native-windows-gui/examples/dialog_multithreading_d.rs">Multithreading</a>: shows two UI running in their own GUI thread.</li>
        </ul>
        <br/>

    </div>
</div>

<script src="style/rustbook.js"></script>
</body>
</html>
